package com.admin_system.service;

import com.admin_system.pojo.Material;
import org.springframework.web.multipart.MultipartFile;

import java.util.List;
import java.util.Map;

/**
 * 物料服务接口
 * 定义了处理物料相关业务的核心功能
 * 包括物料的上传、下载、查询和删除等操作
 */
public interface MaterialService {
    
    /**
     * 获取所有物料列表
     * 查询系统中所有已上传的物料资源
     *
     * @return 物料对象列表，如果没有物料则返回空列表
     */
    List<Material> getAllMaterials();
    
    /**
     * 根据ID获取特定物料
     * 通过唯一标识符查找物料资源
     *
     * @param id 物料唯一标识ID
     * @return 物料对象，如果不存在则返回null
     */
    Material getMaterialById(Long id);
    
    /**
     * 保存物料文件
     * 将用户上传的文件保存到服务器并创建相应的物料记录
     *
     * @param file 上传的物料文件
     * @param description 物料描述信息
     * @return 创建成功的物料对象
     * @throws Exception 上传过程中可能发生的异常
     */
    Material saveMaterial(MultipartFile file, String description) throws Exception;
    
    /**
     * 获取物料文件资源
     * 根据物料ID获取对应的文件资源，用于下载或预览
     *
     * @param id 物料ID
     * @return 包含文件资源对象和文件名的Map
     *         - "resource": 文件资源对象(Resource)
     *         - "filename": 文件原始名称(String)
     * @throws Exception 获取文件过程中可能发生的异常
     */
    Map<String, Object> getMaterialFile(Long id) throws Exception;
    
    /**
     * 删除物料
     * 删除指定物料记录及其对应的物理文件
     *
     * @param id 物料ID
     * @throws Exception 删除过程中可能发生的异常
     */
    void deleteMaterial(Long id) throws Exception;
    
    /**
     * 清理孤立的物料文件
     * 删除磁盘上存在但数据库中没有对应记录的物料文件
     *
     * @return 包含成功和失败数量的Map
     * @throws Exception 清理过程中可能发生的异常
     */
    Map<String, Integer> cleanupOrphanedFiles() throws Exception;
} 